home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 26 / CU Amiga Magazine's Super CD-ROM 26 (1998)(EMAP Images)(GB)[!][issue 1998-09].iso / CUCD / PowerPC / uae-0.8.4 / docs / unix / README
Text File  |  1998-04-20  |  12KB  |  248 lines
  1. This file documents the details relevant to the Unix versions of UAE. General
  2. information can be found in the file "README"
  3.  
  4. System requirements
  5. ===================
  6.  
  7. UAE will run on most Unix systems, and by now most of the portability issues
  8. have been sorted out. However, since I am developing UAE using Linux, you may
  9. encounter problems from time to time. If this happens, let me know as soon as
  10. possible so these can be fixed in the next release.
  11.  
  12. These are the requirements for getting the Unix version to run:
  13.   - X11, or SVGAlib if you are using Linux.
  14.   - 8MB RAM (better 16MB) + some swap
  15.   - The 386 is the only CPU that UAE will not run on. You need a 486 or
  16.     higher if you want to use an Intel CPU.
  17.   - an ANSI C compiler. Do not use a K&R compiler, otherwise you risk getting
  18.     incorrect code. GCC is _strongly_ recommended. Don't use versions of GCC
  19.     older than 2.7.2. I wouldn't recommend 2.7.2 either.
  20.   - Optionally, the gtk library, available from ftp.gimp.org, and a pthreads
  21.     library.
  22.  
  23. For reference, this is my system configuration:
  24.   OS: Linux 2.0.33
  25.   CPU: AMD-K6-233
  26.   RAM: 64MB
  27.   X11: version 3.3.2
  28.   Compiler: egcs-1.0.2
  29.   Libraries: glibc-2.0.6 (includes libpthread), gtk-1.0.0
  30.   binutils: 2.9
  31. If you have the same configuration, and it doesn't run, you're doing something
  32. wrong ;)
  33.  
  34.  
  35. Compilation
  36. ===========
  37.  
  38. To build UAE, first unpack it to an appropriate directory (e.g. /usr/src/uae
  39. on a Linux system). The simple way to proceed is to type "configure; make", 
  40. after that has completed you should have a working X11 version of UAE. Ignore
  41. warnings if you get them.
  42.  
  43. However, you should probably have a look at some of the compile-time options
  44. found in "config.h" before you do this. There are some things you can change
  45. there so that the resulting executable will perform better on your machine.
  46. Each of the options in that file has a description. You can edit config.h to
  47. suit your needs; and then do "configure; make" afterwards.
  48.  
  49. When running configure, there are a few options that you can use to
  50. influence configure's decision as to what kind of display should be used.
  51. The following displays are available:
  52.   - Standard X11, in a window. This is the default.
  53.   - X11/DGA. This runs full-screen and is somewhat faster than the normal X11
  54.     code. You need a recent (>= version 3.2) XFree86 X server.
  55.   - SVGAlib. This is only available on Linux systems. It is the default if X11
  56.     is not found by configure.
  57.   - ncurses character output. This is the last resort.
  58.  
  59. Type "configure --help" to get a list of options that configure understands.
  60. The following are likely to be useful:
  61.   --without-x        : Don't use X11 as target.
  62.   --with-svgalib     : Build a version that uses SVGAlib (Linux only)
  63.   --with-ggi         : Build a version that uses GGI (Linux only)
  64.   --with-asciiart    : Build a version that uses ASCII "graphics"
  65.   --enable-sound     : If a sound system is found that UAE knows about, sound
  66.                        emulation will be compiled in.
  67.   --enable-profiling : Build a much slower version of the emulator (if you 
  68.                        don't know what it's for, you don't want it)
  69.   --enable-dga       : If your X server supports the DGA extension, use it
  70.   --enable-vidmode   : If your X server supports the VidMode extension, use
  71.                        it. This enables the emulator to switch to low
  72.                        resolutions such as 320x256 or 400x300 if you have
  73.                defined ModeLines for them.
  74.   --enable-ui        : Build a user interface if possible (enabled by default)
  75.   --enable-threads   : Build UAE multithreaded on systems that support it.
  76.                        Note that there is very little thread support in UAE at
  77.                the moment.
  78.   --enable-penguins  : Enable some additional threads which only make sense on
  79.                        SMP (symmetric multi penguin) machines. If you have a
  80.                single-CPU machine, you don't want to use this option.
  81. Note that there is a corresponding "--disable-xxx" for each "--enable-xxx"
  82. option, and a "--without-yyy" for each "--with-yyy".
  83.  
  84. Both the SVGAlib and the DGA version run full-screen, i.e. you can't run other
  85. programs at the same time very well. You also need to be root to run either of
  86. these two versions.
  87. Making UAE suid root is _not_ a particularly good idea if you care about the
  88. security of your system.
  89.  
  90. If you are not sure whether you have an SMP machine, you don't have one.
  91.  
  92.  
  93. Run-time options
  94. ================
  95.  
  96. The X11 version (without DGA) of UAE understands these special command-line
  97. options:
  98.   -L     : Use "low-bandwidth" mode, which can reduce the amount of data
  99.            transferred between UAE and the X server. That's particularly an
  100.        advantage when these are running on two different machines in a
  101.        network.
  102.   -T     : Use the MIT-SHM extension. This may not be available on all
  103.            machines, and it will not work if UAE and the X server are not
  104.        running on the same machine.
  105.        In all other configurations, turning on this option will give you
  106.        a huge speed improvement.
  107.   -x     : Turn off the X11 mouse cursor for the UAE window. Personally, I
  108.            find that seeing the X cursor helps, but that's a matter of taste.
  109.  
  110. The SVGAlib version understands the following command-line option:
  111.   -x     : Turn off linear frame buffer support, even if it is available.
  112.            Unless linear mode doesn't work properly, you don't want to disable
  113.        it, because UAE is much faster if it can draw into a linear
  114.        frame buffer.
  115.  
  116.  
  117. Keyboard mappings
  118. =================
  119.  
  120. You can exit the SVGAlib (and the DGA) version by pressing the F12 key.
  121. PgUp/PgDn emulate the right/left Amiga keys. In the SVGAlib version, F11 will
  122. bring you back to the user interface screen so you can change disks during the
  123. emulation.
  124.  
  125. The X11 version needs some help to figure out how to map keys: You'll have to
  126. tell it the keyboard language with the "-l" commandline option. Several
  127. languages ("us", "se", "de", "fr", "es", "it") are supported. If you have
  128. a different keyboard, patches to make UAE work with it are appreciated.
  129.  
  130.  
  131. Mouse and joystick emulation
  132. ============================
  133.  
  134. The X11 (non-DGA) version has one problem: There are two mouse pointers, the
  135. X11 mouse pointer and the mouse pointer in the emulator window. You can work
  136. that way, but you get confused quickly.
  137. The solution in previous (0.6.8 and before) versions of UAE was a small piece
  138. of code that looked at the position of sprite 0 on the screen and tried to
  139. generate mouse movements in an emulated hardware port. That worked reasonably
  140. well, but had several problems.
  141. The new solution is to use a small Amiga program which is called "mousehack".
  142. You will find this in the "amiga" subdirectory. Put it into the directory that
  143. you use for harddisk emulation so that you can run it from the emulator. Then
  144. put the command "run >NIL: mousehack" at the top of your startup-sequence. UAE
  145. will detect when this program is running and use the improved mouse pointer
  146. positioning method. (Don't run this program on old versions of UAE)
  147. If the program is not running, you get the old behaviour - almost. By default,
  148. the emulator will no longer try to keep Amiga and X mouse pointers at the same
  149. position, because that led to problems in the past. You can toggle this
  150. behaviour with F12.
  151. (If you just added "run mousehack" to your startup-sequence, that would have
  152. the effect that the initial CLI window would be impossible to close.
  153. Unfortunately, redirecting output to >NIL: disables all error messages that
  154. mousehack can give you - so if it does not work, try running it by hand
  155. without the >NIL: redirection.)
  156.  
  157. If you find a program in which the mouse pointer does not move at all if you
  158. use the X11 version, start that program with mousehack _not_ running
  159. (Magnetic Scrolls adventures are known to need this, for example).
  160.  
  161. The SVGAlib and DGA versions are not affected by any of this (and pressing F12
  162. exits those versions).
  163.  
  164. If you use Linux and have the joystick driver kernel module, "configure"
  165. should automatically enable support for it. UAE calibrates the joystick
  166. automatically. Turn it a few times on startup to get the calibration done. 
  167.  
  168.  
  169. Harddisk emulation
  170. ==================
  171.  
  172. Please read the appropriate sections in the file "README" on how to use the
  173. filesystem emulation. There are a few Unix-specific things about it, though.
  174.  
  175. If you want to execute files located on a native filesystem, they need to have
  176. the x permission bit set. That can be done in Unix by "chmod +x file" or in
  177. AmigaDOS with "protect file rwed".
  178. You should set aside a whole directory tree for AmigaOS files, and not use it
  179. from Unix in any way if you can avoid it. Changing permissions/owners,
  180. creating symbolic links and doing other stuff that AmigaOS does not know about
  181. is a good way to confuse the emulator and the emulated software. E.g. it's
  182. possible to have a symlink pointing at a mounted CD-ROM. The emulator would
  183. see that as a directory inside which it gets "read only filesystem" errors,
  184. and wouldn't know what to do about it. Avoid this sort of thing. It's best to
  185. start with an empty harddisk emulation directory and install software there
  186. only from within the emulation.
  187. The following setup can also lead to problems:
  188.   -m dh0:/foo -m dh1:/foo/bar
  189. Please take care that the filesystems you mount don't overlap each other
  190. (another great reason not to use symbolic links within them).
  191.  
  192.  
  193. Printing
  194. ========
  195.  
  196. If you give UAE the "-p lpr" option, output for the parallel port will be
  197. piped to lpr, which will in turn print it. You should use the Postscript
  198. printer driver on the Amiga side (since UAE relies on the ^D character at
  199. the end of the Postscript output).
  200. Note that I never tried this myself, so you're on your own.
  201.  
  202.  
  203. Transferring things over the serial port
  204. ========================================
  205.  
  206. There's an easy way to use a null-modem cable without terminal software if
  207. you use Linux (and probably other Unices). You can do
  208.  
  209.   transdisk >SER: <options>
  210.  
  211. on the Amiga to copy the data directly to the serial port. Before that, do
  212.  
  213.   cat /dev/ttyS1 >df0.adf
  214.   
  215. on your Linux box to receive the data (it may be ttyS0 on your system, or
  216. another number, depending on which serial port you are using). When the Amiga
  217. is done transferring, hit ^C on the PC to interrupt the cat program. To make
  218. this work, you need to use the same settings for the serial port on both
  219. sides. This is done with the Preferences program on the Amiga (this is split
  220. into several programs from Kickstart 2.0 upwards, you'll find a program called
  221. "serial" in the Prefs directory of your Workbench disk). On the Linux side,
  222. use the stty program. "man stty" will give you the manpage describing how to
  223. use it.
  224. To be on the safe side, set the speed to a low value (2400 baud). Turn off
  225. Xon/Xoff, but enable RTS/CTS.
  226. I use the following command myself:
  227.  
  228.   stty 19200 parenb -cstopb cread clocal crtscts -istrip -inlcr -icrnl -opost
  229.     -onlcr -parodd -isig -icanon -iexten raw cs8 </dev/ttyS1
  230.  
  231. which is probably overkill, but you never know :)
  232. This maps to 19200 baud, 8 bits, even parity, one stop bit, which you have to
  233. set in the Amiga preferences.
  234.  
  235.  
  236. Using the Linux AFFS filesystem
  237. ===============================
  238.  
  239. If you use Linux with a kernel version >= 2.0.7 and version 2.5k of the mount
  240. program, you can do
  241.    mount df0.adf /mnt -t affs -o loop
  242. to mount disk image df0.adf at the mount point /mnt. This is much more
  243. convenient than using the "readdisk" program.
  244.  
  245. You'll need to enable support for the Amiga filesystem and the loop device
  246. when configuring and compiling the kernel (say yes to the "Ask about
  247. experimental drivers" question at the start).
  248.